<HTML>
<HEAD>
<TITLE>[Chapter 7] 7.4 GridLayout</TITLE>
<META NAME="author" CONTENT="John Zukowski">
<META NAME="date" CONTENT="Thu Jul 31 14:39:28 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java AWT">
<META NAME="title" CONTENT="Java AWT">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java AWT" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch07_03.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 7<br>Layouts</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch07_05.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JAWT-CH-7-SECT-4">7.4 GridLayout</A></h2>

<P CLASS=para>
<A NAME="CH07.GRID1"></A><A NAME="CH07.GRID2"></A><A NAME="CH07.GRID3"></A>The <tt CLASS=literal>GridLayout</tt> layout manager 
is ideal for laying out objects in rows and columns, where each cell in 
the layout has the same size. Components are added to the layout from left 
to right, top to bottom. <tt CLASS=literal>setLayout(new GridLayout(2,3)</tt>) changes the <tt CLASS=literal>LayoutManager</tt> 
of the current container to a 2 row by 3 column <tt CLASS=literal>GridLayout</tt>. <A HREF="ch07_04.htm#JAWT-CH-7-FIG-6">Figure 7.6</A> 
shows an applet using this layout.

<DIV CLASS=figure>
<h4 CLASS=figure><A CLASS="TITLE" NAME="JAWT-CH-7-FIG-6">Figure 7.6: Applet using GridLayout</A></h4>


<p>
<img align=middle src="./figs/jawt0706.gif" alt="[Graphic: Figure 7-6]" width=260 height=166 border=0>

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JAWT-CH-7-SECT-4.1">GridLayout Methods</A></h3>Constructors

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public GridLayout () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
This constructor creates a <tt CLASS=literal>GridLayout</tt> 
initially configured to have one row, an infinite number of columns, and 
no gaps. A gap is the space between adjacent components in the horizontal 
or vertical direction. With a gap of zero, components in adjacent cells 
will have no space between them. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public GridLayout (int rows, int columns) </I><br>
<DD>

<P CLASS=para>
This constructor creates a <tt CLASS=literal>GridLayout</tt> 
initially configured to be <tt CLASS=literal>rows</tt> 
x <tt CLASS=literal>columns</tt> in size. The default 
setting for horizontal and vertical gaps is zero pixels. The gap is the 
space between adjacent components in the horizontal and vertical directions. 
With a gap of zero, components in adjacent cells will have no space between 
them. 

<P CLASS=para>
You can set the number of rows or columns to zero; this means that the 
layout will grow without bounds in that direction. If both <tt CLASS=literal>rows</tt> 
and <tt CLASS=literal>columns</tt> are zero, the run-time 
exception <tt CLASS=literal>IllegalArgumentException</tt> 
will be thrown. </DL>
<DIV CLASS=note>
<P CLASS=note><BLOCKQUOTE><P><B>NOTE:</B> 
</blockquote><P>
</DIV>

<P CLASS=para>
The rows and columns passed to the <tt CLASS=literal>GridLayout</tt> 
constructor are only recommended values. It is possible that the system 
will pick other values if the number of objects you add to the layout is 
sufficiently different from the size you requested; for example, you placed 
nine objects in a six-element grid. 
</blockquote><P>
</DIV>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public GridLayout (int rows, int columns, int hgap, int vgap) </I><br>
<DD>

<P CLASS=para>
This version of the constructor is called by the previous one. It creates 
a <tt CLASS=literal>GridLayout</tt> with an initial 
configuration of <tt CLASS=literal>rows</tt> x <tt CLASS=literal>columns</tt>, 
with a horizontal gap of <tt CLASS=literal>hgap</tt> 
and vertical gap of <tt CLASS=literal>vgap</tt>. 
The gap is the space between the different components in the different 
directions, measured in pixels. It is possible to have negative gaps if 
you want components to overlap. 

<P CLASS=para>
You can set the number of rows or columns to zero; this means that the 
layout will grow without bounds in that direction. If both <tt CLASS=literal>rows</tt> 
and <tt CLASS=literal>columns</tt> are zero, the run-time 
exception <tt CLASS=literal>IllegalArgumentException</tt> 
will be thrown. </DL>
Informational methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public int getColumns () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getColumns()</tt> method retrieves 
the current column setting, which may differ from the number of columns 
displayed. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setColumns (int columns) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setColumns()</tt> method changes 
the current column setting to <tt CLASS=literal>columns</tt>. 
After changing the setting, you must <tt CLASS=literal>validate()</tt> 
the <tt CLASS=literal>Container</tt>. If you try to 
set the number of rows and the number of columns to zero, this method throws 
the run-time exception <tt CLASS=literal>IllegalArgumentException</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public int getRows () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getRows()</tt> method retrieves 
the current row setting; this may differ from the number of rows displayed. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setRows (int rows) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setRows()</tt> method changes 
the current row setting to <tt CLASS=literal>rows</tt>. 
After changing the setting, you must <tt CLASS=literal>validate()</tt> 
the <tt CLASS=literal>Container</tt>. If you try to 
set the number of rows and the number of columns to zero, this method throws 
the run-time exception <tt CLASS=literal>IllegalArgumentException</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public int getHgap () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getHgap()</tt> method retrieves 
the current horizontal gap setting. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setHgap (int hgap) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setHgap()</tt> method changes 
the current horizontal gap setting to <tt CLASS=literal>hgap</tt>. 
After changing the gaps, you must <tt CLASS=literal>validate()</tt> 
the <tt CLASS=literal>Container</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public int getVgap () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getVgap()</tt> method retrieves 
the current vertical gap setting. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setVgap (int hgap) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setVgap()</tt> method changes 
the current vertical gap setting to <tt CLASS=literal>vgap</tt>. 
After changing the gaps, you must <tt CLASS=literal>validate()</tt> 
the <tt CLASS=literal>Container</tt>. </DL>
LayoutManager methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public void addLayoutComponent (String name, Component component)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>addLayoutComponent()</tt> method 
of <tt CLASS=literal>GridLayout</tt> does nothing. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void removeLayoutComponent (Component component)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>removeLayoutComponent()</tt> 
method of <tt CLASS=literal>GridLayout</tt> does nothing. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public Dimension preferredLayoutSize (Container target) </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>preferredLayoutSize()</tt> method 
of <tt CLASS=literal>GridLayout</tt> calculates the 
preferred dimensions for the components in <tt CLASS=literal>target</tt>. 
The preferred size depends on the size of the grid, which may not be the 
size requested by the constructor; the <tt CLASS=literal>GridLayout</tt> 
treats the constructor's arguments as recommendations and may ignore 
them if appropriate. 

<P CLASS=para>
The actual number of rows and columns is based upon the number of components 
within the <tt CLASS=literal>Container</tt>. The <tt CLASS=literal>GridLayout</tt> 
tries to observe the number of rows requested first, calculating the number 
of columns. If the requested number of rows is nonzero, the number of 
columns is determined by (# components + rows - 1) / rows. If request 
is for zero rows, the number of rows to use is determined by a similar 
formula: (# components + columns - 1) / columns. <A HREF="ch07_04.htm#JAWT-CH-7-TAB-1">Table 7.1</A> 
demonstrates this calculation. The last entry in this table is of special 
interest: if you request a 3x3 grid but only place four components in the 
layout, you get a 2x2 layout as a result. If you do not want to be surprised, 
size the <tt CLASS=literal>GridLayout</tt> based on 
the number of objects you plan to put into the display. 

<P>
<DIV CLASS=table>
<TABLE BORDER>
<CAPTION><A CLASS="TITLE" NAME="JAWT-CH-7-TAB-1">Table 7.1: GridLayout Row/Column Calculation</A></CAPTION>
<TR CLASS=row>
<TH ALIGN="LEFT">Rows</TH>
<TH ALIGN="LEFT">Columns</TH>
<TH ALIGN="LEFT"># Components</TH>
<TH ALIGN="LEFT">Display Rows</TH>
<TH ALIGN="LEFT">Display Columns</TH>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">0</TD>
<TD ALIGN="LEFT">1</TD>
<TD ALIGN="LEFT">10</TD>
<TD ALIGN="LEFT">10</TD>
<TD ALIGN="LEFT">1</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">0</TD>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">10</TD>
<TD ALIGN="LEFT">5</TD>
<TD ALIGN="LEFT">2</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">1</TD>
<TD ALIGN="LEFT">0</TD>
<TD ALIGN="LEFT">10</TD>
<TD ALIGN="LEFT">1</TD>
<TD ALIGN="LEFT">10</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">0</TD>
<TD ALIGN="LEFT">10</TD>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">5</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">10</TD>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">5</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">20</TD>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">10</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">10</TD>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">4</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">1</TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">3</TD>
<TD ALIGN="LEFT">4</TD>
<TD ALIGN="LEFT">2</TD>
<TD ALIGN="LEFT">2</TD>
</TR>
</TABLE>
<P>
</DIV>
<p>
<DT CLASS=varlistentry><I CLASS=emphasis></I><br>
<DD>

<P CLASS=para>
Once we know the dimensions of the grid, it's easy to compute the 
preferred size for the layout. The <tt CLASS=literal>GridLayout</tt> 
takes the maximum height and maximum width of the preferred sizes for all 
the components in the layout. (Note that the maximum width and maximum 
height aren't necessarily from the same component.) This becomes 
the preferred size of each cell within the layout. The preferred size of 
the layout as a whole is computed using the preferred size of a cell and 
adding gaps and insets as appropriate. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public Dimension minimumLayoutSize (Container target)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>minimumLayoutSize()</tt> method 
of <tt CLASS=literal>GridLayout</tt> calculates the 
minimum dimensions for the components in <tt CLASS=literal>target</tt>. 
First it determines the actual number of rows and columns in the final 
layout, using the method described previously. The <tt CLASS=literal>minimumLayoutSize()</tt> 
method then determines the widest and tallest <tt CLASS=literal>getMinimumSize()</tt> 
of a component, and this becomes the minimum size of a cell within the layout. 
The minimum size of the layout as a whole is computed using the minimum 
size of a cell and adding gaps and insets as appropriate. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void layoutContainer (Container target)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>layoutContainer()</tt> method 
draws <tt CLASS=literal>target</tt>'s components 
on the screen in a series of rows and columns. Each component within a 
<tt CLASS=literal>GridLayout</tt> will be the same 
size, if it is possible. If there is insufficient space for all the components, 
the size of each is reduced proportionally. </DL>
Miscellaneous methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public String toString () </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>toString()</tt> method of <tt CLASS=literal>GridLayout</tt> 
returns a string including the current horizontal and vertical gap settings, 
along with the rows and columns settings. For a <tt CLASS=literal>GridLayout</tt> 
created with 2 rows and 3 columns, the result would be: </DL>
<DIV CLASS=screen>
<P>
<PRE>
java.awt.GridLayout[hgap=0,vgap=0,rows=2,cols=3]
</PRE>
</DIV>

</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch07_03.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch07_05.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>BorderLayout</td>
<td width=171 align=center valign=top><a href="index/idx_a.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>CardLayout</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
